home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 85 / CD Actual 85 Febrero 2004.iso / Experto / Apache / apache_2.0.48-win32-x86-no_ssl.msi / Data.Cab / F251775_apr_tables.h < prev    next >
Encoding:
C/C++ Source or Header  |  2003-06-22  |  17.5 KB  |  461 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2003 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_TABLES_H
  56. #define APR_TABLES_H
  57.  
  58. /**
  59.  * @file apr_tables.h
  60.  * @brief APR Table library
  61.  */
  62.  
  63. #include "apr.h"
  64. #include "apr_pools.h"
  65.  
  66. #if APR_HAVE_STDARG_H
  67. #include <stdarg.h>     /* for va_list */
  68. #endif
  69.  
  70. #ifdef __cplusplus
  71. extern "C" {
  72. #endif /* __cplusplus */
  73.  
  74. /**
  75.  * @defgroup apr_tables Table and Array Functions
  76.  * @ingroup APR 
  77.  * Tables are used to store entirely opaque structures 
  78.  * for applications, while Arrays are usually used to
  79.  * deal with string lists.
  80.  * @{
  81.  */
  82.  
  83. /** the table abstract data type */
  84. typedef struct apr_table_t apr_table_t;
  85.  
  86. /** @see apr_array_header_t */
  87. typedef struct apr_array_header_t apr_array_header_t;
  88.  
  89. /** An opaque array type */
  90. struct apr_array_header_t {
  91.     /** The pool the array is allocated out of */
  92.     apr_pool_t *pool;
  93.     /** The amount of memory allocated for each element of the array */
  94.     int elt_size;
  95.     /** The number of active elements in the array */
  96.     int nelts;
  97.     /** The number of elements allocated in the array */
  98.     int nalloc;
  99.     /** The elements in the array */
  100.     char *elts;
  101. };
  102.  
  103. /**
  104.  * The (opaque) structure for string-content tables.
  105.  */
  106. typedef struct apr_table_entry_t apr_table_entry_t;
  107.  
  108. /** The type for each entry in a string-content table */
  109. struct apr_table_entry_t {
  110.     /** The key for the current table entry */
  111.     char *key;          /* maybe NULL in future;
  112.                          * check when iterating thru table_elts
  113.                          */
  114.     /** The value for the current table entry */
  115.     char *val;
  116.  
  117.     /** A checksum for the key, for use by the apr_table internals */
  118.     apr_uint32_t key_checksum;
  119. };
  120.  
  121. /**
  122.  * Get the elements from a table
  123.  * @param t The table
  124.  * @return An array containing the contents of the table
  125.  */
  126. APR_DECLARE(const apr_array_header_t *) apr_table_elts(const apr_table_t *t);
  127.  
  128. /**
  129.  * Determine if the table is empty
  130.  * @param t The table to check
  131.  * @return True if empty, False otherwise
  132.  */
  133. APR_DECLARE(int) apr_is_empty_table(const apr_table_t *t);
  134.  
  135. /**
  136.  * Determine if the array is empty
  137.  * @param a The array to check
  138.  * @return True if empty, False otherwise
  139.  */
  140. APR_DECLARE(int) apr_is_empty_array(const apr_array_header_t *a);
  141.  
  142. /**
  143.  * Create an array
  144.  * @param p The pool to allocate the memory out of
  145.  * @param nelts the number of elements in the initial array
  146.  * @param elt_size The size of each element in the array.
  147.  * @return The new array
  148.  */
  149. APR_DECLARE(apr_array_header_t *) apr_array_make(apr_pool_t *p,
  150.                                                  int nelts, int elt_size);
  151.  
  152. /**
  153.  * Add a new element to an array
  154.  * @param arr The array to add an element to.
  155.  * @return Location for the new element in the array.
  156.  * @remark If there are no free spots in the array, then this function will
  157.  *         allocate new space for the new element.
  158.  */
  159. APR_DECLARE(void *) apr_array_push(apr_array_header_t *arr);
  160.  
  161. /**
  162.  * Remove an element from an array
  163.  * @param arr The array to remove an element from.
  164.  * @return Location of the element in the array.
  165.  * @remark If there are no elements in the array, NULL is returned.
  166.  */
  167. APR_DECLARE(void *) apr_array_pop(apr_array_header_t *arr);
  168.  
  169. /**
  170.  * Concatenate two arrays together
  171.  * @param dst The destination array, and the one to go first in the combined 
  172.  *            array
  173.  * @param src The source array to add to the destination array
  174.  */
  175. APR_DECLARE(void) apr_array_cat(apr_array_header_t *dst,
  176.                     const apr_array_header_t *src);
  177.  
  178. /**
  179.  * Copy the entire array
  180.  * @param p The pool to allocate the copy of the array out of
  181.  * @param arr The array to copy
  182.  * @return An exact copy of the array passed in
  183.  * @remark The alternate apr_array_copy_hdr copies only the header, and arranges 
  184.  *         for the elements to be copied if (and only if) the code subsequently
  185.  *         does a push or arraycat.
  186.  */
  187. APR_DECLARE(apr_array_header_t *) apr_array_copy(apr_pool_t *p,
  188.                                       const apr_array_header_t *arr);
  189. /**
  190.  * Copy the headers of the array, and arrange for the elements to be copied if
  191.  * and only if the code subsequently does a push or arraycat.
  192.  * @param p The pool to allocate the copy of the array out of
  193.  * @param arr The array to copy
  194.  * @return An exact copy of the array passed in
  195.  * @remark The alternate apr_array_copy copies the *entire* array.
  196.  */
  197. APR_DECLARE(apr_array_header_t *) apr_array_copy_hdr(apr_pool_t *p,
  198.                                       const apr_array_header_t *arr);
  199.  
  200. /**
  201.  * Append one array to the end of another, creating a new array in the process.
  202.  * @param p The pool to allocate the new array out of
  203.  * @param first The array to put first in the new array.
  204.  * @param second The array to put second in the new array.
  205.  * @return A new array containing the data from the two arrays passed in.
  206. */
  207. APR_DECLARE(apr_array_header_t *) apr_array_append(apr_pool_t *p,
  208.                                       const apr_array_header_t *first,
  209.                                       const apr_array_header_t *second);
  210.  
  211. /**
  212.  * Generates a new string from the apr_pool_t containing the concatenated 
  213.  * sequence of substrings referenced as elements within the array.  The string 
  214.  * will be empty if all substrings are empty or null, or if there are no 
  215.  * elements in the array.  If sep is non-NUL, it will be inserted between 
  216.  * elements as a separator.
  217.  * @param p The pool to allocate the string out of
  218.  * @param arr The array to generate the string from
  219.  * @param sep The separator to use
  220.  * @return A string containing all of the data in the array.
  221.  */
  222. APR_DECLARE(char *) apr_array_pstrcat(apr_pool_t *p,
  223.                       const apr_array_header_t *arr,
  224.                       const char sep);
  225.  
  226. /**
  227.  * Make a new table
  228.  * @param p The pool to allocate the pool out of
  229.  * @param nelts The number of elements in the initial table.
  230.  * @return The new table.
  231.  * @warning This table can only store text data
  232.  */
  233. APR_DECLARE(apr_table_t *) apr_table_make(apr_pool_t *p, int nelts);
  234.  
  235. /**
  236.  * Create a new table and copy another table into it
  237.  * @param p The pool to allocate the new table out of
  238.  * @param t The table to copy
  239.  * @return A copy of the table passed in
  240.  */
  241. APR_DECLARE(apr_table_t *) apr_table_copy(apr_pool_t *p,
  242.                                           const apr_table_t *t);
  243.  
  244. /**
  245.  * Delete all of the elements from a table
  246.  * @param t The table to clear
  247.  */
  248. APR_DECLARE(void) apr_table_clear(apr_table_t *t);
  249.  
  250. /**
  251.  * Get the value associated with a given key from the table.  After this call,
  252.  * The data is still in the table
  253.  * @param t The table to search for the key
  254.  * @param key The key to search for
  255.  * @return The value associated with the key
  256.  */
  257. APR_DECLARE(const char *) apr_table_get(const apr_table_t *t, const char *key);
  258.  
  259. /**
  260.  * Add a key/value pair to a table, if another element already exists with the
  261.  * same key, this will over-write the old data.
  262.  * @param t The table to add the data to.
  263.  * @param key The key fo use
  264.  * @param val The value to add
  265.  * @remark When adding data, this function makes a copy of both the key and the
  266.  *         value.
  267.  */
  268. APR_DECLARE(void) apr_table_set(apr_table_t *t, const char *key,
  269.                                 const char *val);
  270.  
  271. /**
  272.  * Add a key/value pair to a table, if another element already exists with the
  273.  * same key, this will over-write the old data.
  274.  * @param t The table to add the data to.
  275.  * @param key The key to use
  276.  * @param val The value to add
  277.  * @warning When adding data, this function does not make a copy of the key or 
  278.  *          the value, so care should be taken to ensure that the values will 
  279.  *          not change after they have been added..
  280.  */
  281. APR_DECLARE(void) apr_table_setn(apr_table_t *t, const char *key,
  282.                                  const char *val);
  283.  
  284. /**
  285.  * Remove data from the table
  286.  * @param t The table to remove data from
  287.  * @param key The key of the data being removed
  288.  */
  289. APR_DECLARE(void) apr_table_unset(apr_table_t *t, const char *key);
  290.  
  291. /**
  292.  * Add data to a table by merging the value with data that has already been 
  293.  * stored
  294.  * @param t The table to search for the data
  295.  * @param key The key to merge data for
  296.  * @param val The data to add
  297.  * @remark If the key is not found, then this function acts like apr_table_add
  298.  */
  299. APR_DECLARE(void) apr_table_merge(apr_table_t *t, const char *key,
  300.                                   const char *val);
  301.  
  302. /**
  303.  * Add data to a table by merging the value with data that has already been 
  304.  * stored
  305.  * @param t The table to search for the data
  306.  * @param key The key to merge data for
  307.  * @param val The data to add
  308.  * @remark If the key is not found, then this function acts like apr_table_addn
  309.  */
  310. APR_DECLARE(void) apr_table_mergen(apr_table_t *t, const char *key,
  311.                                    const char *val);
  312.  
  313. /**
  314.  * Add data to a table, regardless of whether there is another element with the
  315.  * same key.
  316.  * @param t The table to add to
  317.  * @param key The key to use
  318.  * @param val The value to add.
  319.  * @remark When adding data, this function makes a copy of both the key and the
  320.  *         value.
  321.  */
  322. APR_DECLARE(void) apr_table_add(apr_table_t *t, const char *key,
  323.                                 const char *val);
  324.  
  325. /**
  326.  * Add data to a table, regardless of whether there is another element with the
  327.  * same key.
  328.  * @param t The table to add to
  329.  * @param key The key to use
  330.  * @param val The value to add.
  331.  * @remark When adding data, this function does not make a copy of the key or the
  332.  *         value, so care should be taken to ensure that the values will not 
  333.  *         change after they have been added..
  334.  */
  335. APR_DECLARE(void) apr_table_addn(apr_table_t *t, const char *key,
  336.                                  const char *val);
  337.  
  338. /**
  339.  * Merge two tables into one new table
  340.  * @param p The pool to use for the new table
  341.  * @param overlay The first table to put in the new table
  342.  * @param base The table to add at the end of the new table
  343.  * @return A new table containing all of the data from the two passed in
  344.  */
  345. APR_DECLARE(apr_table_t *) apr_table_overlay(apr_pool_t *p,
  346.                                              const apr_table_t *overlay,
  347.                                              const apr_table_t *base);
  348.  
  349. /**
  350.  * Declaration prototype for the iterator callback function of apr_table_do()
  351.  * and apr_table_vdo().
  352.  * @param rec The data passed as the first argument to apr_table_[v]do()
  353.  * @param key The key from this iteration of the table
  354.  * @param value The value from this iteration of the table
  355.  * @remark Iteration continues while this callback function returns non-zero.
  356.  * To export the callback function for apr_table_[v]do() it must be declared 
  357.  * in the _NONSTD convention.
  358.  */
  359. typedef int (apr_table_do_callback_fn_t)(void *rec, const char *key, 
  360.                                                     const char *value);
  361.  
  362. /** 
  363.  * Iterate over a table running the provided function once for every
  364.  * element in the table.  If there is data passed in as a vararg, then the 
  365.  * function is only run on those elements whose key matches something in 
  366.  * the vararg.  If the vararg is NULL, then every element is run through the
  367.  * function.  Iteration continues while the function returns non-zero.
  368.  * @param comp The function to run
  369.  * @param rec The data to pass as the first argument to the function
  370.  * @param t The table to iterate over
  371.  * @param ... The vararg.  If this is NULL, then all elements in the table are
  372.  *            run through the function, otherwise only those whose key matches
  373.  *            are run.
  374.  * @return FALSE if one of the comp() iterations returned zero; TRUE if all
  375.  *            iterations returned non-zero
  376.  * @see apr_table_do_callback_fn_t
  377.  */
  378. APR_DECLARE_NONSTD(int) apr_table_do(apr_table_do_callback_fn_t *comp,
  379.                                      void *rec, const apr_table_t *t, ...);
  380.  
  381. /** 
  382.  * Iterate over a table running the provided function once for every
  383.  * element in the table.  If there is data passed in as a vararg, then the 
  384.  * function is only run on those element's whose key matches something in 
  385.  * the vararg.  If the vararg is NULL, then every element is run through the
  386.  * function.  Iteration continues while the function returns non-zero.
  387.  * @param comp The function to run
  388.  * @param rec The data to pass as the first argument to the function
  389.  * @param t The table to iterate over
  390.  * @param vp The vararg table.  If this is NULL, then all elements in the 
  391.  *                table are run through the function, otherwise only those 
  392.  *                whose key matches are run.
  393.  * @return FALSE if one of the comp() iterations returned zero; TRUE if all
  394.  *            iterations returned non-zero
  395.  * @see apr_table_do_callback_fn_t
  396.  */
  397. APR_DECLARE(int) apr_table_vdo(apr_table_do_callback_fn_t *comp,
  398.                                void *rec, const apr_table_t *t, va_list vp);
  399.  
  400. /** flag for overlap to use apr_table_setn */
  401. #define APR_OVERLAP_TABLES_SET   (0)
  402. /** flag for overlap to use apr_table_mergen */
  403. #define APR_OVERLAP_TABLES_MERGE (1)
  404. /**
  405.  * For each element in table b, either use setn or mergen to add the data
  406.  * to table a.  Which method is used is determined by the flags passed in.
  407.  * @param a The table to add the data to.
  408.  * @param b The table to iterate over, adding its data to table a
  409.  * @param flags How to add the table to table a.  One of:
  410.  *          APR_OVERLAP_TABLES_SET        Use apr_table_setn
  411.  *          APR_OVERLAP_TABLES_MERGE      Use apr_table_mergen
  412.  * @remark  This function is highly optimized, and uses less memory and CPU cycles
  413.  *          than a function that just loops through table b calling other functions.
  414.  */
  415. /**
  416.  *<PRE>
  417.  * Conceptually, apr_table_overlap does this:
  418.  *
  419.  *  apr_array_header_t *barr = apr_table_elts(b);
  420.  *  apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts;
  421.  *  int i;
  422.  *
  423.  *  for (i = 0; i < barr->nelts; ++i) {
  424.  *      if (flags & APR_OVERLAP_TABLES_MERGE) {
  425.  *          apr_table_mergen(a, belt[i].key, belt[i].val);
  426.  *      }
  427.  *      else {
  428.  *          apr_table_setn(a, belt[i].key, belt[i].val);
  429.  *      }
  430.  *  }
  431.  *
  432.  *  Except that it is more efficient (less space and cpu-time) especially
  433.  *  when b has many elements.
  434.  *
  435.  *  Notice the assumptions on the keys and values in b -- they must be
  436.  *  in an ancestor of a's pool.  In practice b and a are usually from
  437.  *  the same pool.
  438.  * </PRE>
  439.  */
  440.  
  441. APR_DECLARE(void) apr_table_overlap(apr_table_t *a, const apr_table_t *b,
  442.                                      unsigned flags);
  443.  
  444. /**
  445.  * Eliminate redunandant entries in a table by either overwriting
  446.  * or merging duplicates
  447.  *
  448.  * @param t Table.
  449.  * @param flags APR_OVERLAP_TABLES_MERGE to merge, or
  450.  *              APR_OVERLAP_TABLES_SET to overwrite
  451.  */
  452. APR_DECLARE(void) apr_table_compress(apr_table_t *t, unsigned flags);
  453.  
  454. /** @} */
  455.  
  456. #ifdef __cplusplus
  457. }
  458. #endif
  459.  
  460. #endif    /* ! APR_TABLES_H */
  461.